<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Enabling the remote API - server side</title>
<link rel="stylesheet" type="text/css" href="../style.css">
</head>

<body>

<div align="center">
<table class=allEncompassingTable >
 <tr>
  <td >
<p><a href="../index.html" TARGET="_top"><img src="images/homeImg.png"></a></p>



<h1>Enabling the remote API - server side</h1>

<p class=warningBox>The remote API, or <em>legacy remote API</em>, should not be mixed-up with the <a href="b0RemoteApiOverview.htm">B&Oslash;-based remote API</a>, which is a newer version of the remote API that is more flexible, easier to use and most importantly, much simpler to extend.</p>

<p>
The remote API server side is implemented via a <a href="plugins.htm">CoppeliaSim plugin</a> that is based on the <a href="apiOverview.htm">regular API</a>. The remote API plugin project is located <a href="https://github.com/CoppeliaRobotics/simExtRemoteApi" target="_blank">here</a>. Should you miss one specific function, then you can  implement it yourself into the remote API framework (see also the section on <a href="remoteApiExtension.htm">extending the remote API</a>). </p>
<p>To enable the remote API on the server side (i.e. on CoppeliaSim's side), make sure the remote API plugin was successfully loaded at CoppeliaSim start-up (simExtRemoteApi.dll, libsimExtRemoteApi.dylib or libsimExtRemoteApi.so) (you can inspect the console window for information related to plugin loading). The remote API plugin can start as many server services as needed (each service will be listening/communicating on a different port). A server service can be started in two different ways:</p>

<li><a name="continuousRemoteApiService" id="continuousRemoteApiService"></a>At CoppeliaSim start-up (<strong>continuous remote API server service</strong>). The remote API plugin will try reading a configuration file named <em>remoteApiConnections.txt</em> and according to its content, start appropriate server services. Have a look at the  configuration file for details. Use this method for remote control of the simulator itself. With this method remote API functions will always be executed on the server side, even if simulation is not running (which is not always the case with next method here below). There is another method to start a continuous remote API server service, via the <a href="commandLine.htm">command line</a>.</li>
<li><a name="temporaryRemoteApiService" id="temporaryRemoteApiService"></a>From within a <a href="scripts.htm">script</a> (<strong>temporary remote API server service</strong>). This is most of the time the preferred method of starting a remote API server service. The user is in control when the service is started or stopped. When a temporary remote API server service is started from a <a href="simulationScripts.htm">simulation script</a> however, the service will automatically be stopped at simulation end. A temporary remote API server service can be started or stopped with following 2 custom Lua functions (the 2 functions are exported by the plugin): </li>


<h3 class=subsectionBarTab><a name="simExtRemoteApiStart" id="simExtRemoteApiStart"></a><a name="simRemoteApi.start" id="simRemoteApi.start"></a>simRemoteApi.start</h3>
<table class=apiTableTab>
<tr class=apiTableTr> 
<td class=apiTableLeftDescr>
Description 
</td> 
<td class=apiTableRightDescr>
Starts a temporary remote API server service on the specified port. When started from a <a href="simulationScripts.htm">simulation script</a>, the service will automatically end when the simulation finishes</td>
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLSyn>
Lua synopsis
</td> 
<td class=apiTableRightLSyn>number result=simRemoteApi.start(number portNumber,number maxPacketSize=1300,Boolean debug=false,Boolean preEnableTrigger=false)<br></td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLParam>Lua parameters</td> 
<td class=apiTableRightLParam>
<div><strong>portNumber</strong>: port where to install the server service. Ports above 20000 are preferred. Negative port numbers can be specified in order to use shared memory, instead of socket communication.</div>
<div><strong>maxPacketSize</strong>: the maximum size of a socket send-packet. Make sure to keep the value at 1300, unless the client side has a different setting.</div>
<div><strong>debug</strong>: if true, a window will display the data traffic on that port.</div>
<div><strong>preEnableTrigger</strong>: if true, the server service will be pre-enabled for synchronous trigger signals from the client.</div>
</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLRet>
Lua return values
</td> 
<td class=apiTableRightLRet>
<div>-1 if operation was not successful</div>
<div></div></td> 
</tr> 
</table> 
<br>











<h3 class=subsectionBarTab><a name="simExtRemoteApiStop" id="simExtRemoteApiStop"></a><a name="simRemoteApi.stop" id="simRemoteApi.stop"></a>simRemoteApi.stop</h3>
<table class=apiTableTab>
<tr class=apiTableTr> 
<td class=apiTableLeftDescr>
Description 
</td> 
<td class=apiTableRightDescr>
Stops a temporary remote API server service on the specified port</td>
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLSyn>
Lua synopsis
</td> 
<td class=apiTableRightLSyn>number result=simRemoteApi.stop(number portNumber)</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLParam>Lua parameters</td> 
<td class=apiTableRightLParam>
<div><strong>portNumber</strong>: port where the server service is running</div>
</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLRet>
Lua return values
</td> 
<td class=apiTableRightLRet>
<div>-1 if operation was not successful</div>
<div></div></td> 
</tr> 
</table> 
<br>


<br>
<p>
You can gather information about any remote API server service with following custom Lua function (the function is exported by the plugin):
</p>






<h3 class=subsectionBar><a name="simExtRemoteApiStatus" id="simExtRemoteApiStatus"></a><a name="simRemoteApi.status" id="simRemoteApi.status"></a>simRemoteApi.status</h3>
<table class=apiTable>
<tr class=apiTableTr> 
<td class=apiTableLeftDescr>
Description 
</td> 
<td class=apiTableRightDescr>
Fetches information about a server service. Use this function to enumerate all server services running.</td>
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLSyn>
Lua synopsis
</td> 
<td class=apiTableRightLSyn>number status, table_5 info, number serverVersion, number clientVersion, string clientIp=simRemoteApi.status(number portNumber)</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLParam>Lua parameters</td> 
<td class=apiTableRightLParam>
<div><strong>portNumber</strong>: port where the server service is running.</div>
</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLRet>
Lua return values
</td> 
<td class=apiTableRightLRet>
<div><strong>status</strong>: -1 if no service is running on the given port. Otherwise a bit-coded value:</div>
<div class=tab>bit 0: communication thread is running</div>
<div class=tab>bit 1: client is connected</div>
<div><strong>info</strong>: nil if no service is running at the given index. Otherwise following values:</div>
<div class=tab>info[1]: time when last client request was received</div>
<div class=tab>info[2]: time when last client request was replied</div>
<div class=tab>info[3]: time that passed between 2 successive requests from the client side</div>
<div class=tab>info[4]: number of commands received during last client request</div>
<div class=tab>info[5]: number of commands sent during last reply to client</div>
<div><strong>serverVersion</strong>: the version of the remote API server plugin</div>
<div><strong>clientVersion</strong>: the version of the remote API client, or -1 if that information is not (yet) available</div>
<div><strong>clientIp</strong>: the IP address of the connected client</div>
</td> 
</tr> 
</table> 
<br>


<br>



<p>
You can reset (i.e. destroy and recreate) any remote API server service with following custom Lua function (the function is exported by the plugin):
</p>






<h3 class=subsectionBar><a name="simExtRemoteApiReset" id="simExtRemoteApiReset"></a><a name="simRemoteApi.reset" id="simRemoteApi.reset"></a>simRemoteApi.reset</h3>
<table class=apiTable>
<tr class=apiTableTr> 
<td class=apiTableLeftDescr>
Description 
</td> 
<td class=apiTableRightDescr>Resets a remote API server service on the specified port. This is equivalent to call <a href="#simRemoteApi.stop">simRemoteApi.stop</a> followed by <a href="#simRemoteApi.start">simRemoteApi.start</a>, but also works for <a href="#continuousRemoteApiService">continuous remote API server services</a>. This can be useful to force disconnection from a client.</td>
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLSyn>
Lua synopsis
</td> 
<td class=apiTableRightLSyn>number result=simRemoteApi.reset(number portNumber)</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLParam>Lua parameters</td> 
<td class=apiTableRightLParam>
<div><strong>portNumber</strong>: port where the server service is running.</div>
</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLRet>
Lua return values
</td> 
<td class=apiTableRightLRet>
<div>-1 if operation was not successful</div>
</td> 
</tr> 
</table> 
<br>






<br>
<h3 class=recommendedTopics>Recommended topics</h3>
<li><a href="remoteApiClientSide.htm">Enabling the remote API - client side</a></li>
<li><a href="legacyRemoteApiOverview.htm">Remote API overview</a></li>
<li><a href="remoteApiModusOperandi.htm">Remote API modus operandi</a></li>
<li><a href="remoteApiFunctionListAlphabetical.htm">Alphabetical remote API function list</a></li>
<li><a href="remoteApiConstants.htm">Remote API constants</a></li>
<br>
<br>
 </tr>
</table> 
</div>  
  
  
</body>

</html>